BigDFT.PDoS module

This module offers a suite of tools for calculating and analyzing the projected density of states (PDoS) in molecular systems. It provides functionality to extract projection information from cubic and linear scaling PDoS calculations, and compute weights associated with each projection.

Examples: The module includes two example functions (_example_cubic and _example_linear) to demonstrate usage with cubic and linear scaling PDoS calculations, respectively.

cubic_projection_info(log)[source]

Extracts projection information from a cubic scaling Projected Density of States (PDoS) calculation, as performed in a BigDFT run.

This function processes the output log file from a cubic scaling BigDFT calculation to map each atom in the system to its projections, such as ‘s’, ‘px’, ‘py’, ‘pz’, etc. The function is designed to work with the specific structure of BigDFT log files, particularly extracting information from the ‘Mulliken Charge Population Analysis’ section.

Parameters:

log (BigDFT.Logfiles.Logfile) – A BigDFT log file object, containing the results of a cubic scaling calculation with the pdos option on.

Returns:

A nested dictionary where the first key is the atomic symbol, and the second key is the projection type. The value is a list of indices, each corresponding to a projection of that type for the atom. For example: {‘C’: {‘s’: [0], ‘px’: [1], ‘py’: [2], ‘pz’: [3]}}.

Return type:

dict of dict of list

cubic_projection_weights(log, proj_info, log_dir='.')[source]

Calculates the weights associated with each projection from a cubic scaling Projected Density of States (PDoS) calculation.

This function interprets the PDoS data stored in a BigDFT log file to compute the weights of different atomic projections (e.g., ‘s’, ‘px’, ‘py’, ‘pz’) for each orbital. It utilizes the projection information obtained from cubic_projection_info and the PDoS data file (‘pdos.dat’).

Parameters:
  • log (BigDFT.Logfiles.Logfile) – The BigDFT log file object from a cubic scaling PDoS calculation.

  • proj_info (dict) – A dictionary mapping atomic symbols to projection types and indices, as returned by cubic_projection_info. log_dir (str, optional): The directory where the BigDFT log file is located. Defaults to the current directory (“.”).

Returns:

A list where each element corresponds to an orbital. Each element is a dict, mapping atomic types to another dict, which in turn maps projections to their weights. For example, if you want the weight of the first orbital for the ‘s’ projection of Carbon, it would be accessed as weights[0][‘C’][‘s’].

Return type:

list of dict

compute_weight(evec, sks_evec, orb_idx, proj_idx)[source]

Computes the weight of a specific projection for a given orbital in the projected density of states (PDoS) calculation, typically used in the linear scaling mode.

This function calculates the contribution of a specified set of projections (identified by their indices) to a particular orbital, based on the eigenvectors of the system. The function allows for optional inclusion of the overlap matrix (s) and the density matrix (k) if you’re doing Mulliken analysis or projecting out virtuals, respectively.

Parameters:
  • evec (numpy.array) – Array of eigenvectors, where each column represents an eigenvector of the system.

  • evec – Overlap * Density * Overlap * evec. Overlap allows you to do a Mulliken projection, and Density can be used to filter in energy. If you’re doing Lowdin, just use the density. If you don’t need to filter in energy, the identity matrix can be used for the density.

  • orb_idx (int) – Index of the orbital for which the weight is being computed.

  • proj_idx (list of int) – List of indices corresponding to the projections included in the weight calculation.

Returns:

the calculated weight.

Return type:

(float)

linear_projection_info(log, thresh=0.3)[source]

Analyze and categorize projection types for each atom in the system based on electrostatic multipole information from a given log file.

This function processes the electrostatic multipoles associated with atoms in a system and classifies each support function (such as ‘s’, ‘px’, ‘py’, ‘pz’, ‘dxy’, etc.) based on their multipole expansion.

Parameters:
  • log (BigDFT.Logfiles.Logfile) – The log file object from a BigDFT run.

  • thresh (float) – the threshold used for determining the character of a multipole.

Returns:

A nested dictionary where the first key is the atomic symbol, the second key is the projection type, and the value is a list of indices associated with that projection type for the given atom. Example: {‘H’: {‘s’: [0]}, ‘O’: {‘px’: [1], ‘py’: [2], ‘pz’: [3]’}}

Return type:

dict of dict of list

Raises:
  • ValueError – If the projection type cannot be determined for an atom

  • based on the heuristic criteria.

linear_projection_weights(evec, proj_info, s, k)[source]

Computes the weights associated with a set of projections for each eigenvalue in a linear scaling Projected Density of States (PDoS) calculation.

This function uses the eigenvectors and eigenvalues of a system, along with projection information (such as atomic symbols and projection types), to calculate the contribution of these projections to each eigenvalue.

The function allows for inclusion of the overlap matrix (s) and the density matrix (k) if you’re doing Mulliken analysis or projecting out virtuals, respectively. If you’re doing Lowdin, pass the Lowdin orthogonalized eigenvectors and the identity matrix for s. You’re doing Mulliken, and don’t want to project out virtuals, pass the overlap matrix as K.

Parameters:
  • evec (numpy.array) – Array of eigenvectors, where each column represents an eigenvector of the system.

  • proj_info (dict) – Dictionary mapping atom symbols to projections, and projections to indices, as obtained from linear_projection_info.

  • s (numpy.array) – Overlap matrix, used in the calculation of the weights

  • k (numpy.array) – Density matrix, used in the calculation of the weights

Returns:

A list where each element corresponds to an eigenvalue. Each element is a dict, mapping atomic types to another dict, which in turn maps projections to their computed weights. For example, weights[0][‘C’][‘s’] would access the weight of ‘s’ projection for Carbon for the first eigenvalue.

Return type:

list of dict

compute_fragment_weights(sys, log, evec, s, k)[source]

Computes the weights associated with fragments in a system for each eigenvalue for a Fragment Projected Density of States (PDoS) calculation.

Parameters:
  • sys (BigDFT.Systems.System) – The system object as defined in BigDFT, representing the fragments of the system.

  • log (BigDFT.Logfiles.Logfile) – The log file object from a BigDFT run computed in the linear scaling mode.

  • evec (numpy.array) – Array of eigenvectors, where each column represents an eigenvector of the system.

  • s (numpy.array) – Overlap matrix, used in the calculation of the weights

  • k (numpy.array) – Density matrix, used in the calculation of the weights

Returns:

A list where each element corresponds to an eigenvalue. Each element is a dict, mapping fragment identifiers to their computed weights. For example, weights[0][‘HOH:1’] accesses the weight of fragment ‘HOH:1’ for the first eigenvalue.

Return type:

list of dict

compute_SFs_weights(evec, metadata, mapping)[source]

Computes the support functions weights from the mapped indices

Parameters:
  • evec (numpy.array) – Array of eigenvectors

  • metadata (BigDFT.Spillage.MatrixMetadata) – The information

  • indexing (on the matrices) –

  • mapping (dict) – The instruction to fold the eigenvectors

Returns:

A list where each element corresponds to an eigenvalue. Each element is a dict, mapping SFs to their computed weights.

Return type:

list of dict

_example_cubic()[source]

The following is an example of module usage:

# System
from BigDFT.Database.Molecules import get_molecule
sys = get_molecule("H2O")

# Input file
from BigDFT.Inputfiles import Inputfile
inp = Inputfile()
inp.set_hgrid(0.4)
inp.set_xc("PBE")
inp.calculate_pdos()

# Calculate
from BigDFT.Calculators import SystemCalculator
code = SystemCalculator(skip=True, verbose=False)
log = code.run(sys=sys, input=inp, name="pdos-C")

# Get weights
proj_list = cubic_projection_info(log)
weights = cubic_projection_weights(log, proj_list)

print(weights[0]["O"]["s"])
print(weights[1]["H"]["s"])
_example_linear()[source]

The following is an example of module usage:

# System
from BigDFT.Database.Molecules import get_molecule
sys = get_molecule("H2O")

# Input file
from BigDFT.Inputfiles import Inputfile
inp = Inputfile()
inp.set_hgrid(0.4)
inp.set_xc("PBE")
inp["import"] = "linear"
inp["lin_general"] = {"support_function_multipoles": True}

from BigDFT.Calculators import SystemCalculator
code = SystemCalculator(skip=True, verbose=False)
log = code.run(sys=sys, input=inp, name="pdos-L")

# Read the matrices
from BigDFT.PostProcessing import BigDFTool
tool = BigDFTool()
h = tool.get_matrix_h(log)
s = tool.get_matrix_s(log)
k = tool.get_matrix_k(log)

# Diagonalize
from scipy.linalg import eigh
evals, evec = eigh(h.todense(), b=s.todense())

# Get the weights
proj_info = linear_projection_info(log)
weights = linear_projection_weights(evec, proj_info, s=s, k=0.5 * k)
print(weights[0]["O"]["s"])
print(weights[1]["H"]["s"])